<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<link rel="Stylesheet" type="text/css" media="screen" href="Screen.css" />
	<title>STP_CreateBridge</title>
</head>
<body>
	<h3>STP_CreateBridge</h3>
	<hr />
	<h4>Declaration</h4>
	<pre>struct STP_BRIDGE* STP_CreateBridge
(
    unsigned int                portCount,
    unsigned int                mstiCount,
    unsigned int                maxVlanNumber,
    const struct STP_CALLBACKS* callbacks,
    const unsigned char         bridgeAddress[6],
    unsigned int                debugLogBufferSize
);</pre>
	<h4>Summary</h4>
	<p>Creates an STP bridge and returns an STP_BRIDGE* object.</p>
	<h4>Parameters</h4>
	<dl>
		<dt>portCount</dt>
		<dd>The maximum number of ports this bridge will have. Usually equal to the number
			of physical ports present on the device, minus the management port.</dd>
		<dt>mstiCount</dt>
		<dd>Maximum number of MSTIs for when the device runs MSTP (this is in addition to the CIST, which is always present).
			Should be zero if your device supports only STP/RSTP, or 0..64 if your device supports also MSTP.
			Passing an invalid value will cause an assertion failure in the function.
		</dd>
		<dt>maxVlanNumber</dt>
		<dd>The maximum VLAN number your device supports while in MSTP mode, or otherwise zero. The library uses this to determine the size of an&nbsp;
            MST Configuration Table that it holds internally and from which it calculates the MST
            Configuration Digest. See also <a href="STP_SetMstConfigTable.html">STP_SetMstConfigTable</a>
			and <a href="STP_GetMstConfigTable.html">STP_GetMstConfigTable</a>.</dd>
		<dt>callbacks</dt>
		<dd>Pointer to an <a href="STP_CALLBACKS.html">STP_CALLBACKS</a> structure containing
            pointers to application-defined STP callbacks. The STP library makes a copy of this
            structure, so the application can reuse it after the function returns.
		</dd>
		<dt>bridgeAddress</dt>
		<dd>The MAC address of the STP bridge, usually equal to the MAC address of the
			Ethernet peripheral of the management microcontroller/processor.
			See the Remarks section at
			<a href="STP_SetBridgeAddress.html">STP_SetBridgeAddress</a> for information
			about this address. </dd>
		<dt>debugLogBufferSize</dt>
		<dd>The size of the debug log buffer this function will allocate, if <a href="STP_EnableLogging.html">STP_USE_LOG=0 is not defined</a> in the compiler options. Must be >= 2.
		</dd>
	</dl>
	<h4>Return value</h4>
	<dl>
		<dd>A pointer to an STP_BRIDGE object. This pointer is used for uniquely identifying the bridge while
			calling various other STP functions, such as <a href="STP_DestroyBridge.html">STP_DestroyBridge</a>.
		</dd>
	</dl>
	<h4>Remarks</h4>
	<p>
		This functions allocates all the memory required for running the bridge,
		and it does so only using the STP callback <code>
			<a href="StpCallback_AllocAndZeroMemory.html">allocAndZeroMemory</a></code>. No other STP
		function allocates memory. This allows the application programmer to determine empirically
		the memory requirement of the STP library for a given bridge. The memory requirement
		depends, among other things, on the number of ports, the number of spanning trees, and the
		debug log size. This memory requirement never changes between successive executions of the
		program.</p>
	<p>
		This function sets all operational parameters
		(such as ForwardDelay, HelloTime, bridge priority, port priority etc.) to their default values from the 802.1Q standard.</p>
	<p>
		This function initializes the bridge for RSTP operation. If you need to switch to Legacy STP or MSTP, call <a href="STP_SetStpVersion.html">STP_SetStpVersion</a>.</p>
	<p>
		This function does not start the bridge (i.e., does not begin execution of the bridge&#39;s
		state machines). The application must explicitly start the bridge by calling <a href="STP_StartBridge.html">
		STP_StartBridge</a>, usually after setting some operational parameters.</p>
	<p>
		The STP library generates debug log text and passes it to the application
		via <code><a href="StpCallback_DebugStrOut.html">StpCallback_DebugStrOut</a></code>. This callback in turn usually sends this text
		to a PC via some "debug connection". For best performance, this log should be larger
		for packet-based connections such as Ethernet, and smaller for non-packet-based connections
		such as serial.
	</p>
	<p>
		Logging of debug text is disabled when this function returns.
		The application can enable it
		with <a href="STP_EnableLogging.html">STP_EnableLogging</a>.</p>
	<p>
		This function creates a default MST Configuration Identifier as
		follows:</p>
	<ul>
		<li><em>ConfigurationIdentifierFormatSelector</em> is zero.</li>
		<li><em>ConfigurationName</em> is generated from the <code>bridgeAddress</code> parameter and has the
			format aa:bb:cc:dd:ee:ff. The library will <em>not</em> update this default name if the
			application later changes the MAC address of the bridge with <a href="STP_SetBridgeAddress.html">STP_SetBridgeAddress</a>.
			The application can later change this name by calling
			<a href="STP_SetMstConfigName.html">STP_SetMstConfigName</a>.&nbsp; </li>
		<li><em>RevisionLevel</em> is zero.</li>
		<li><em>ConfigurationDigest</em> is 0xAC36177F50283CD4B83821D8AB26DE62, which corresponds to
			a mapping in which all VIDs are mapped to the CIST, no VID is mapped to any MSTI.</li>
		<li>The mapping of VIDs to MSTIs, which can be retrieved with
			<a href="STP_GetMstConfigTable.html">STP_GetMstConfigTable</a>, is all zeroes.</li>
	</ul>

	<p>
		The STP library is not
		reentrant, so it is not thread-safe in any way. If the STP library is used in a multi-threaded
		application, it is recommended that all library functions are called from the same
		thread; the library will, in turn, call all its <a href="STP_CALLBACKS.html">callbacks</a>
		on that thread.</p>
	<p>
		Since the library is not reentrant, you must not call library functions from an interrupt
		handler in an embedded application.</p>
</body>
</html>
